The Events Subsystem PDF file shipped with ODF release 1 contains several inaccuracies which could not be updated before the release. Please check the ODF web page at /www.devtools.apple.com/odf/ where we will post an updated version of the Developer's Guide as soon as possible or use this document (and the various Engineering Notes) to make sure that you have the latest information.
The page numbers used below are the document page numbers, not the PDF file page numbers. The document starts at page 395.
Page 401. Event Focus
The focus set is now maintained at the presentation level (field fFocusSet in FW_CPresentation), each frame of the same presentation share the same foci. By default presentations are created with all common foci (key, menu, selection, clipboard). Modal dialogs are created with the modal focus.
The class FW_CFocusSet doesn't exist anymore. To change the focus of a frame you can use FW_CPresentation::AdoptFocusSet. Following ODF naming conventions "Adopt" means that the focus set will be deleted when the presentation object goes away. This method can be used to replace an existing focus set or to create an empty focus set if you pass NULL (Do not use the method SetFocusSet directly unless you are implementing a behavior like in the Button sample)
Warning: no frame of a given presentation should be active when changing the focus set because it is used during activation/deactivation events.
The ODF Button sample shows how to change the focus to detect a mouse click inside an embedded frame, see the source in part.cpp.
Page 408. Target Chain Management
WillingToResign() was renamed WantsToResign().
ODFrameToEventHandler is obsolete. The paragraph starting with "The Events subsystem allows you to use OpenDoc frames as ODF event handlers." should be removed.
returns the location in content coordinates. theODWindow is the current OpenDoc window, theGC is usually an instance of FW_CViewContext in which case the location is relative to this view's content (you can also use an instance of FW_CScreenContext to get a global mouse location on the screen).
Typically you access theODWindow from the current facet the following way:
returns the location in frame coordinates. facet is the current OpenDoc facet, typically accessed through a mouse event with FW_CMouseEvent::GetFacet(ev).
Only FW_IsKeyPressed is available. To check for a particular key such as Command, Control, Option or Shift you can call FW_IsKeyPressed with the corresponding virtual key code defined in FWEveDef.h. For example FW_IsKeyPressed(FW_kVKCommand) returns if the command key is down.
Important: FW_IsKeyPressed returns the current state of the keyboard, i.e. whether a key is down at the time of the call. It doesn't tell you if a key was pressed at the time of an event you may be processing now. In particular you should not use this method to check for the presence of modifiers in keyboard events! Use FW_CSystemEvent::GetModifiers.
Page 414. FW_WaitFor
Waits for a specified number of Macintosh "ticks" (1 tick is about 1/60 second).
Page 415. FW_CActivateEvent
This is the Class representing window activation events, not part activation events.
The window activation is the traditional activate/deactivate events sent by the MacOS when a window comes to the front or is pushed behind. The part activation is the OpenDoc event when a part's frame acquires the selection focus (you can detect it with the frame's FocusStateChanged method).
The description of the implementation of FW_CEventDispatcher::DispatchMouseDownEvent is not accurate because of several function renamings. Look at the source code in FWEventD.cpp if you are curious.
Page 472. FW_CMouseEvent::GetMousePosition
coordinate can be kScreen, kWindow or kFrame. If you want the position relative to the view where the mouse click occured you can use FW_CView::FrameToView or FW_CView::FrameToViewContent. Once you have a point in frame coordinates you can also find the inner most view containing it with FW_CSuperView::GetViewContaining.
Page 485. FW_CSystemEvent Methods
The method IsShitModifier was added. Returns true if the Shift key was pressed at the time of the event.
Page 485. FW_CVirtualKeyEvent Methods
The method IsCommandPeriod was added. Returns true if both the command and period keys were pressed at the time of the event. This is used by FW_CDialogFrame to simulate a click in the Cancel button.
Page 495-498. FW_MEventHandler Methods
The following methods were removed:
IsActive, Activate and Deactivate
The active property is either on the frame (part activation) or on the window (standard window activation). A frame is active when it has the selection focus, use FW_CFrame::HasSelectionFocus. Use the OpenDoc method IsActive on the ODWindow object to check if a window is active.
GetIdentifier and SetIdentifier
Event handlers don't contain ids anymore, they must be identified by pointers. However most event handlers are views and views do have ids. See FW_CView::GetViewId.
GetEventHandlerContaining
Hit testing is done with FW_CSuperView::GetViewContaining.
TargetValidationSucceeded, TargetValidationFailed
These tests can be implemented with the other target methods.
HandleActivate, DoActivate
HandleMouseEnter, DoMouseEnter
HandleMouseLeave, DoMouseLeave
HandleMouseWithin, DoMouseWithin
HandleSuspendResume, DoSuspendResume
HandleWindowEvent, DoWindowEvent
All these events are now handled in FW_CFrame and propagated to FW_CView obejcts when necessary.
